Intent

pr #492 is trying to finish the cursor-specific user experience around discord slash commands without turning openab into a cursor workaround layer.

the concrete problem is twofold. first, cursor-backed channels currently miss the intended /models, /agents, and /cancel control path because the handlers assume a session already exists and can run out of time against discord's 3 second interaction deadline. second, cursor-agent exposes broken ACP behavior around model selection, so the pr also tightens the docs to explain what openab will and will not do when the backend lies.

assumption: deploy-time cursor support already exists in-tree through the existing cursor image, helm values, and docs, so this pr is intentionally about discord interaction flow and policy boundary, not first-time packaging.

Feat

this is a feature and interaction-hardening pass centered in src/discord.rs, with supporting docs and config example updates.

in plain terms, it makes cursor sessions behave like a real first-class ACP backend for discord controls:

• slash commands defer immediately so slow or cold session startup does not blow the interaction deadline
• the handler creates or restores the pooled ACP session before reading cached configOptions
• /agents works for both category=agent and category=mode
• /models respects discord's 25-option select limit with a plain in-order truncation
• /cancel becomes usable against an active cursor session through the same deferred-response pattern
• docs now state that --model auto is load-bearing and that openab passes cursor soft rejects through instead of probing or auto-falling back

notably, the ACP transport, pool internals, and config parsing layer stay untouched. that is a good boundary.

Who It Serves

the primary beneficiary is discord users running openab against cursor-agent acp, especially users on a fresh channel session who previously hit the "start a conversation first" dead-end or a silent timeout.

secondarily it serves maintainers and deployers. the docs now make the startup model invariant and upstream cursor-agent defects explicit, which reduces false debugging loops where openab gets blamed for cursor's bad protocol behavior.

Rewritten Prompt

implement cursor-compatible discord config controls without adding cursor-specific heuristics to the ACP layer.

acceptance criteria:

• /models, /agents, and /cancel must call defer_ephemeral before any potentially slow work
• config commands must call pool.get_or_create(thread_key) before reading configOptions, so they work on cold-start sessions and after pool eviction
• config select handling must re-run get_or_create before set_config_option
• build_config_select must treat agent and mode as aliases and cap string select menus to 25 options in order
• successful config changes must be acknowledged via edit_response
• failures to create a session or set an option must surface a direct error in the interaction response
• docs/cursor.md and config.toml.example must explain that --model auto is required for true auto routing
• openab must not probe, string-match, or auto-fallback after set_config_option; upstream cursor-agent ACP defects remain documented in #493

validation:

• manual e2e against a live cursor-agent deployment for /models, /agents, and /cancel
• verify cold-start command use works before the first normal prompt
• verify a pool-evicted session can still switch config after the menu interaction

if issue #489 still has deployer ergonomics left over, split them into a follow-up instead of growing this pr sideways.

Merge Pitch

this is worth merging because it closes a real product gap for cursor-backed deployments with relatively tight scope. users get the same slash-command control surface other ACP backends already expose, and the implementation does it in the right layer: discord handler and docs, not protocol-shaping hacks.

risk is moderate but localized. the code changes sit in interaction timing and pooled session bootstrapping, which can regress command UX if wrong, but they do not alter the ACP core. the likely reviewer concern is not the handler logic itself. it is whether this pr is claiming to close more than it actually does, because #489 originally mixed UI wiring, deploy config, and a probe-based workaround that the project has since rejected.

Best-Practice Comparison

OpenClaw: the relevant principle is boundary discipline. route work explicitly, surface failures honestly, and do not smuggle backend-specific recovery rules into the wrong layer. this pr matches that better than the earlier probe-and-fallback direction. durable job persistence and retry/backoff are not directly relevant here because this is an interactive discord control path, not a scheduled execution pipeline.

Hermes Agent: the relevant principle is making state transitions explicit before acting. the defer-first plus get_or_create flow is a small but meaningful version of that: establish session state before assuming cached config exists. file locking, atomic writes, and fresh-session scheduling are not relevant to this path.

net: the useful lesson from both reference systems is not their runtime architecture. it is their refusal to paper over undefined state with wishful logic. #492 is stronger after removing the proactive probe because it keeps openab's contract clean.

Implementation Options

1. merge this pr as the narrow discord-and-docs slice, and split any remaining cursor deployer ergonomics into a separate follow-up.

2. broaden this pr slightly to also add or normalize default cursor deployment artifacts if maintainers still think #489 requires a repo-native config entry point beyond the existing helm/docs path.

3. reintroduce an openab-side probe, entitlement filter, or auto-fallback layer to hide cursor-agent's broken model semantics from users.

Comparison Table

Recommendation

take option 1.

the pr is strongest when treated as a focused interaction-layer improvement plus documentation cleanup. it fixes a real user-facing gap, keeps the ACP boundary honest, and avoids merging policy-confused workaround code just because cursor-agent is sloppy. if maintainers still want a dedicated config/cursor.toml, compose profile, or similar deploy-time artifact, do that as a follow-up and do not use it to block the handler fix.

the one thing to watch in review is scope accounting: if #489 is meant to cover more than this pr actually ships, close only the part that is now done and leave the rest as explicit follow-up work.

🔴 Changes requested — The core approach is sound, but the PR needs a rebase onto current main to integrate with the pagination system (build_config_components, build_pagination_buttons, handle_pagination) instead of regressing it. The agent/mode alias and defer_ephemeral pattern should be preserved during rebase.

1. What problem does this solve?

Discord slash commands (/models, /agents, /cancel) had two UX issues against cursor-agent:

1. 3-second deadline: CreateInteractionResponse must be sent within 3s of the interaction. Cold-starting an ACP session (spawning cursor-agent acp) can exceed this, causing a "This interaction failed" error.
2. "Start a conversation first" dead-end: If no session existed (user never @mentioned the bot), /models returned "No model options available" with no way to recover.
3. Category mismatch: cursor-agent uses category: "mode" while kiro-cli uses category: "agent" — /agents returned empty against cursor-agent.

2. How does it solve them?

Three changes in src/discord.rs:

• defer_ephemeral + EditInteractionResponse: Buys time by deferring the response, then editing it after the ACP call completes. Applied to /models, /agents, /cancel, and the config select handler.
• get_or_create pre-flight: Before fetching configOptions, ensures an active ACP session exists. Handles both never-started and pool-evicted sessions.
• agent/mode aliasing: build_config_select now treats "agent" and "mode" as aliases, so /agents works against both kiro-cli and cursor-agent.

Additionally:

• Pagination removed: build_pagination_buttons, build_config_components, handle_pagination all deleted. Replaced with a plain take(25) in build_config_select. Since Discord caps StringSelectMenu at 25 options and cursor-agent returns 26 on Pro, only the last one is dropped.

3. What was considered?

The PR description documents three iterations:

• v1: Proactive per-model probe (silent ping to detect soft-rejects) + auto-fallback to default[]
• v2: Probe removed per maintainer feedback — trust-the-protocol approach
• v3: Truncation pinning (current + default[] always included) also removed — plain take(25)

Good evolution. Each simplification is well-justified.

4. Is this the best approach?

The defer + get_or_create + aliasing approach is correct. Two concerns:

1. Pagination removal is a regression for future backends: cursor-agent returns 26 models (one dropped), but a future backend could return 50+. The pagination code was already working. Removing it saves ~60 lines but loses functionality. Consider keeping it or at minimum documenting the 25-option hard cap as a known limitation.
2. Aliasing is hardcoded: The agent/mode alias table is a match block. If a third backend uses yet another category name, this needs another code change. A config-driven alias map would be more extensible, but this is a NIT — the current approach is fine for two known backends.

🔴 SUGGESTED CHANGES

1. Rebase onto main — 168 commits behind, merge state is CONFLICTING. The diff cannot be reviewed for correctness against current main until conflicts are resolved. This is the only blocker.

2. Missing Prior Art section — Per RFC: PR Contribution Guidelines, PRs should include research on how OpenClaw and Hermes Agent handle the same problem (Discord interaction deadline management, config option menus). The PR description is otherwise excellent — adding this section would complete it.

🟡 NIT

3. Pagination removal trade-off — The removed pagination was functional and handled >25 options gracefully. take(25) silently drops options. Consider either (a) keeping pagination, or (b) adding a log warning when options are truncated so operators know items were dropped:

   if opt.options.len() > DISCORD_SELECT_MAX {
       tracing::warn!(category, total = opt.options.len(), shown = DISCORD_SELECT_MAX, "config options truncated to Discord limit");
   }

4. No tests for aliasing logic — The agent/mode alias matching in build_config_select is new logic with no unit test. A small test with category: "mode" input matched by "agent" lookup would prevent regressions.

5. handle_config_select double get_or_create — The select interaction can only arrive if the user already has an active session (they just saw the menu). The get_or_create call is defensive but adds latency. Consider documenting why it is needed (pool eviction between interactions) in a code comment — the current comment is good but could note the expected frequency.

🟢 INFO

6. Excellent PR description — The revision history (v1→v2→v3) is a model for how to document design evolution. The test plan with specific E2E scenarios against a real cursor-agent pod is thorough.

7. Docs changes are high quality — The startup default table in docs/cursor.md is immediately useful. The soft-reject documentation and upstream ACP compliance gaps section (linking to tracking: cursor-agent ACP compliance issues — upstream bugs affecting /models #493) are exactly the kind of operational knowledge that saves debugging time.

8. Trust-the-protocol principle — The decision to not work around cursor-agent's setOk:true for unroutable models is architecturally correct. Workarounds in the gateway layer create coupling; surfacing the upstream bug directly is the right call.

9. config.toml.example comment — Small but valuable: documenting that --model auto is load-bearing prevents a common misconfiguration.